home *** CD-ROM | disk | FTP | other *** search
/ Chip 2005 June / ccd0605.iso / Software / Freeware / Programare / highlight / highlight-W32GUI-2.2-10b-Setup.exe / {app} / README_INDENT.txt < prev    next >
Text File  |  2004-11-27  |  12KB  |  562 lines
  1. -------------------------------------------------------------------------------
  2. ---  ARTISTIC STYLE MANUAL ----------------------------------------------------
  3. -------------------------------------------------------------------------------
  4.  
  5. This file is based on the original Astyle (http://astyle.sourceforge.net)
  6. manual. Some parts were stripped, and the command line parameters of AStyle
  7. were replaced by the corresponding Highlight parameters.
  8. You can see from the code samples below how the parameters take effect on
  9. the generated source code.
  10.  
  11. AndrΘ Simon, July 2004
  12. ---
  13.  
  14.  
  15. Artistic Style
  16. -------------------------------------------------------------------------------
  17.  
  18. *A Free, Fast & Small Automatic Formatter for C, C++ and Java source code*
  19.  
  20. :Author:     Tal Davidson
  21. :Email:      mail//:davidsont@bigfoot.com
  22. :Homepage:   http://astyle.sourceforge.net
  23. :Date:       May 2002
  24. :Version:    1.13.8
  25. :Edited:     Paul Agapow, July 2003
  26.  
  27. -------------------------------------------------------------------------------
  28.  
  29. Artistic Style is a reindenter and reformatter of C++, C and Java
  30. source code.
  31.  
  32. When indenting source code, we as programmers have a tendency to use
  33. both spaces and tab characters to create the wanted indentation.
  34. Moreover, some editors by default insert spaces instead of tabs when
  35. pressing the tab key, and other editors (Emacs for example) have the
  36. ability to "pretty up" lines by automatically setting up the white space
  37. before the code on the line, possibly inserting spaces in a code that up
  38. to now used only tabs for indentation.
  39.  
  40. Since the NUMBER of space characters showed on screen for each tab
  41. character in the source code changes between editors (until the user
  42. sets up the number to his liking...), one of the standard problems
  43. facing programmers when moving from one source code editor to another
  44. is that code containing both spaces and tabs that was up to now
  45. perfectly indented, suddently becomes a mess to look at when changing to
  46. another editor. Even if you as a programmer take care to ONLY use spaces
  47. or tabs, looking at other peoples source code can still be problematic.
  48.  
  49. To address this problem I have created Artistic Style - a series of
  50. filters, written in C++, that automatically reindent & reformat
  51. C/C++/Java source files. These can be used from a command line, or it
  52. can be incorporated as classes in another C++ program.
  53.  
  54. Please read the license <license.html>. Artistic Style may be used and
  55. distributed under EITHER the *Artistic License* or the *GNU General Public
  56. License (GPL)*.
  57.  
  58.  
  59. Predefined indentation and reformatting styles
  60. -------------------------------------------------------------------------------
  61.  
  62. Apply an indentation scheme with --format-style.
  63.  
  64. --format-style=ansi
  65.  
  66.     ANSI style formatting/indenting::
  67.  
  68.         namespace foospace
  69.         {
  70.             int Foo()
  71.             {
  72.                 if (isBar)
  73.                 {
  74.                     bar();
  75.                     return 1;
  76.                 }
  77.                 else
  78.                     return 0;
  79.             }
  80.         }
  81.  
  82. --format-style=kr
  83.  
  84.     Kernighan&Ritchie style formatting/indenting::
  85.  
  86.         namespace foospace {
  87.             int Foo() {
  88.                 if (isBar) {
  89.                     bar();
  90.                     return 1;
  91.                 } else
  92.                     return 0;
  93.             }
  94.         }
  95.  
  96. --format-style=linux
  97.  
  98.     Linux style formatting/indenting (brackets are broken apart from
  99.     class/function declarations, but connected to command lines, and indents
  100.     are set to 8 spaces)::
  101.  
  102.         namespace foospace
  103.         {
  104.                 int Foo()
  105.                 {
  106.                         if (isBar) {
  107.                                 bar();
  108.                                 return 1;
  109.                         } else
  110.                                 return 0;
  111.                 }
  112.         }
  113.  
  114. --format-style=gnu
  115.  
  116.     GNU style formatting/indenting::
  117.  
  118.         namespace foospace
  119.           {
  120.             int Foo()
  121.               {
  122.                 if (isBar)
  123.                   {
  124.                     bar();
  125.                     return 1;
  126.                   }
  127.                 else
  128.                   return 0;
  129.               }
  130.         }
  131.  
  132. --format-style=java
  133.  
  134.     Java style formatting/indenting::
  135.  
  136.         class foospace {
  137.             int Foo() {
  138.                 if (isBar) {
  139.                     bar();
  140.                     return 1;
  141.                 } else
  142.                     return 0;
  143.             }
  144.         }
  145.  
  146. -------------------------------------------------------------------------------
  147.  
  148. The following indentation options are currently available:
  149.  
  150. $INDENT-SPACES=<num>
  151.     Indent using <num> spaces per indent
  152.  
  153. $INDENT-CLASSES=<true / false>
  154.     Indent `class` blocks so that the headers `public:`, `protected:` and
  155.     `private:` are indented in the class block. The default::
  156.  
  157.         class Foo
  158.         {
  159.         public:
  160.             Foo();
  161.             virtual ~Foo();
  162.         };
  163.  
  164.     becomes::
  165.  
  166.         class Foo
  167.         {
  168.             public:
  169.                 Foo();
  170.                 virtual ~Foo();
  171.         };
  172.  
  173. $INDENT-SWITCHES=<true / false>
  174.     Indent `switch` blocks so that the `case XXX:` headers are indented in
  175.     the class block. The default::
  176.  
  177.         switch (foo)
  178.         {
  179.         case 1:
  180.             a += 2;
  181.             break;
  182.  
  183.         default:
  184.             a += 2;
  185.             break;
  186.         }
  187.  
  188.     becomes::
  189.  
  190.         switch (foo)
  191.         {
  192.             case 1:
  193.                 a += 2;
  194.                 break;
  195.  
  196.             default:
  197.                 a += 2;
  198.                 break;
  199.         }
  200.  
  201. $INDENT-CASES=<true / false>
  202.     Indent `case XXX:` lines so that they are flush with the lines under
  203.     them. The default::
  204.  
  205.         switch (foo)
  206.         {
  207.         case 1:
  208.             {
  209.                 a += 2;
  210.                 break;
  211.             }
  212.  
  213.         default:
  214.             {
  215.                 a += 2;
  216.                 break;
  217.             }
  218.         }
  219.  
  220.     becomes::
  221.  
  222.         switch (foo)
  223.         {
  224.             case 1:
  225.             {
  226.                 a += 2;
  227.                 break;
  228.             }
  229.  
  230.             default:
  231.             {
  232.                 a += 2;
  233.                 break;
  234.             }
  235.         }
  236.  
  237. $INDENT-BRACKETS=<true / false>
  238.     Add extra indentation to brackets. The default::
  239.  
  240.         if (isFoo)
  241.         {
  242.             bar();
  243.         }
  244.         else
  245.         {
  246.             anotherBar();
  247.         }
  248.  
  249.     becomes::
  250.  
  251.         if (isFoo)
  252.             {
  253.             bar();
  254.             }
  255.         else
  256.             {
  257.             anotherBar();
  258.             }
  259.  
  260. $INDENT-BLOCKS=<true / false>
  261.     Add extra indentation to entire blocks. The default::
  262.  
  263.         if (isFoo)
  264.         {
  265.             bar();
  266.         }
  267.         else
  268.             anotherBar();
  269.  
  270.     becomes::
  271.  
  272.         if (isFoo)
  273.             {
  274.                 bar();
  275.             }
  276.         else
  277.             anotherBar();
  278.  
  279. $INDENT-NAMESPACES=<true / false>
  280.     Add extra indentation to namespaces. The default::
  281.  
  282.         namespace foospace
  283.         {
  284.         class Foo
  285.         {
  286.             public:
  287.                 Foo();
  288.                 virtual ~Foo();
  289.         };
  290.         }
  291.  
  292.     becomes::
  293.  
  294.         namespace foospace
  295.         {
  296.             class Foo
  297.             {
  298.                 public:
  299.                     Foo();
  300.                     virtual ~Foo();
  301.             };
  302.         }
  303.  
  304. $INDENT-LABELS=<true / false>
  305.     Add extra indentation to labels so they they appear 1 indent less than
  306.     the current indentation, rather than being flushed to the left. The
  307.     default::
  308.  
  309.         int foospace()
  310.         {
  311.             while (isFoo)
  312.             {
  313.                 ...
  314.                 goto error;
  315.  
  316.         error:
  317.                 ...
  318.             }
  319.         }
  320.  
  321.     becomes::
  322.  
  323.         int foospace()
  324.         {
  325.             while (isFoo)
  326.             {
  327.                 ...
  328.                 goto error;
  329.  
  330.             error:
  331.                 ...
  332.             }
  333.         }
  334.  
  335. $MAX-INSTATEMENT-INDENT=<num>
  336.     Indent a maximal # spaces in a continuous statement, relatively to the
  337.     previous line (e.g. `--max-instatement-indent=40`).
  338.  
  339. $MIN-CONDITIONAL-INDENT=<num>
  340.     Set the minimal indent that is added when a header is built of
  341.     multiple-lines. This indent makes helps to easily separate the header
  342.     from the command statements that follow. The default setting for this
  343.     option is twice the current indent. (e.g.`--min-conditional-indent=8`).
  344.     The default::
  345.  
  346.         // default setting makes this non-bracketed code clear
  347.         if (a < b
  348.                 || c > d)
  349.             foo++;
  350.  
  351.         // but creates an exaggerated indent in this bracketed code
  352.         if (a < b
  353.                 || c > d)
  354.         {
  355.             foo++;
  356.         }
  357.  
  358.     When setting `--min-conditional=0`::
  359.  
  360.         // setting makes this non-bracketed code less clear
  361.         if (a < b
  362.             || c > d)
  363.             foo++;
  364.  
  365.         // but makes this bracketed code prettier
  366.         if (a < b
  367.             || c > d)
  368.         {
  369.             foo++;
  370.         }
  371.  
  372. -------------------------------------------------------------------------------
  373.  
  374. The following formatting options are currently available:
  375.  
  376. $BRACKETS=<break>
  377.     Break brackets  from their pre-block statements (i.e. ANSI C, C++
  378.     style)::
  379.  
  380.         if (isFoo)
  381.         {
  382.             bar();
  383.         }
  384.         else
  385.         {
  386.             anotherBar();
  387.         }
  388.  
  389. $BRACKETS=<attach>
  390.     Attach brackets to their pre-block statements (i.e. Java, K&Rstyle)::
  391.  
  392.         if (isFoo){
  393.             bar();
  394.         } else {
  395.             anotherBar();
  396.         }
  397.  
  398. $BRACKETS=<linux>
  399.     Break brackets from class/function declarations, but attach brackets to
  400.     pre-block command statements::
  401.  
  402.         namespace foospace
  403.         {
  404.             int Foo()
  405.             {
  406.                 if (isBar) {
  407.                     bar();
  408.                     return 1;
  409.                 } else
  410.                     return 0;
  411.             }
  412.         }
  413.  
  414. $BRACKETS=<break-closing-headers>
  415.     When used with either `--brackets=attach` or `--brackets=linux`, breaks
  416.     closing headers (e.g. `else`, `catch`, ...) from their immediately
  417.     preceding closing brackets::
  418.  
  419.         if (isFoo) {
  420.             bar();
  421.         }else {
  422.             anotherBar();
  423.         }
  424.  
  425.     becomes::
  426.  
  427.         if (isFoo) {
  428.             bar();
  429.         }
  430.         else {
  431.             anotherBar();
  432.         }
  433.  
  434. $BREAK-BLOCKS=<true | false>
  435.     Pad empty lines around header blocks (e.g. `if`, `while`...)::
  436.  
  437.         isFoo = true;
  438.         if (isFoo) {
  439.             bar();
  440.         } else {
  441.             anotherBar();
  442.         }
  443.         isBar = false;
  444.  
  445.     becomes::
  446.  
  447.         isFoo = true;
  448.  
  449.         if (isFoo) {
  450.             bar();
  451.         } else {
  452.             anotherBar();
  453.         }
  454.  
  455.         isBar = false;
  456.  
  457. $BREAK-BLOCKS=<all>
  458.     Pad empty lines around header blocks (e.g. `if`, `while` ...). Treat
  459.     closing header blocks (e.g. `else`, `catch`) as stand-alone blocks::
  460.  
  461.         isFoo = true;
  462.         if (isFoo) {
  463.             bar();
  464.         } else {
  465.             anotherBar();
  466.         }
  467.         isBar = false;
  468.  
  469.     becomes::
  470.  
  471.         isFoo = true;
  472.  
  473.         if (isFoo) {
  474.             bar();
  475.  
  476.         } else {
  477.             anotherBar();
  478.         }
  479.  
  480.         isBar = false;
  481.  
  482. $BREAK-ELSEIFS=<true / false>
  483.     Break `else if()` header combinations into seperate lines::
  484.  
  485.         if (isFoo) {
  486.             bar();
  487.         } else if (isBar()){
  488.             anotherBar();
  489.         }
  490.  
  491.     becomes::
  492.  
  493.         if (isFoo) {
  494.             bar();
  495.         } else
  496.             if (isBar()){
  497.                 anotherBar();
  498.             }
  499.  
  500. $ONE-LINE=<keep-statements>
  501.     Don't break complex statements and multiple statements residing in a
  502.     single line.  Thus the following code remains as is::
  503.  
  504.         if (isFoo)
  505.         {
  506.             isFoo = false; cout << isFoo << endl;
  507.         }
  508.  
  509.         if (isFoo) DoBar();
  510.  
  511. $ONE-LINE=<keep-blocks>
  512.     Don't break one-line blocks. Thus the following code remains as is::
  513.  
  514.         if (isFoo)
  515.         { isFoo = false; cout << isFoo << endl; }
  516.  
  517. $PAD=<oper>
  518.     Insert space padding around operators only::
  519.  
  520.         if (isFoo)
  521.             a = bar((b-c)*a,d--);
  522.  
  523.     becomes::
  524.  
  525.         if (isFoo)
  526.             a = bar((b - c) * a, d--);
  527.  
  528. $PAD=<paren>
  529.     Insert space padding around parentheses only::
  530.  
  531.         if (isFoo)
  532.            a = bar((b-c)*a,*d--);`
  533.  
  534.     becomes::
  535.  
  536.         if ( isFoo )
  537.             a = bar( ( b-c )*a, d-- );
  538.  
  539. $PAD=<all>
  540.     Insert space padding around operators AND parentheses::
  541.  
  542.         if (isFoo)
  543.             a = bar((b-c)a,d--);
  544.  
  545.     becomes::
  546.  
  547.         if ( isFoo )
  548.             a = bar( ( b - c ) * a, d-- );
  549.  
  550.  
  551.  
  552. Artistic Style Acknowledgements
  553. -------------------------------------------------------------------------------
  554.  
  555. Thanks to: Jim Watson, Fred Shwartz, W. Nathaniel Mills III, Danny
  556. Deschenes, Andre Houde, Richard Bullington, Paul-Michael Agapow, Daryn
  557. Adler for their patches and contributions to Artistic Style !!! Special
  558. thanks to Richard Bullington and MicroState <http://www.microstate.com> for
  559. giving Artistic Style its mailing-list !!! Special thanks to SourceForge
  560. <http://www.sourceforge.net> for giving Artistic Style its home !!!
  561. Thanks to all the dedicated beta-testers and bug notifiers !!!
  562.